This document describes !WinEdit as currently implemented; it also includes
some historical information.

The following is a summary of changes made since revision 1.5:

 1.07  13-Apr-94  MFC
  Correct description of "Align" action.

 1.06  11-Apr-94  MFC
  Updated to reflect current state of application (version 1.06).
  Replaced ResEd by WinEdit.


----------------------------------------------------------------
$Header: Spec,v 1.5 93/02/01 15:56:59 steve Locked $
$Log:   Spec,v $
# Revision 1.5  93/02/01  15:56:59  steve
# Removed the option buttons that select text/sprite
# labels in the Label and Display fields.  Instead we'll
# just see which have strings in and which don't.
# 
# Revision 1.4  93/01/11  12:47:30  steve
# Added note about OK and Cancel in item flag dialogs
# 
# Revision 1.3  92/10/13  12:17:21  steve
# FormEd -> ResEd
# 
# Revision 1.2  92/10/05  16:59:31  steve
# Altered way icon numbers are stored for composites
# Added menu button and adjuster buttons
# 
# Revision 1.1  92/10/02  12:31:48  steve
# Initial revision
# 
----------------------------------------------------------------

Interface Editor
================

1. Introduction
===============

This is a suggestion for a first stage of work. It allows work on the
toolbox itself to happen in parallel. It would be useful in its own right.

End result - an editor of conformant dialogue boxes in Template files, and a
careful and trustworthy spec of those conformant dialogue boxes.

We do not propose to completely replace the functionality of FormEd at
this stage - FormEd is almost 'too powerful' for normal dialogue box
editing, because it allows many unrecommended objects and structures to
be created.

The program, and resulting Templates, need only work on RISC OS 3.10 or
later.


2. Icon names and numbers
=========================

Before describing the behaviour of this program, a note about icons
and icon numbers. Convenient editing dictates that icons do sometimes
have to be renumbered, in order to control the ordering of icons. For
instance, if a group box is placed around some icons it should always
have a lower number than any of them in order to ensure that they
receive button clicks. Icons are not renumbered unnecessarily, but
when necessary it is done implicitly and without warning.

This leads to the definition of a mechanism of naming icons. An icon
can be given a name through the appearance of an entry in its
validation string. This editor provides facilities for naming icons,
and recommends that these names be used at run-time rather than icon
numbers.  Not all icons need be named, but names should be unique when
they are used.

Also, this editor usually thinks in terms of 'items' rather than icons
within the window, with each item constructed from one or more icons.
This allows it to edit things that cannot be represented as single
icons. For instance, a group box and its label are treated as a single
item, and are edited as such - WinEdit keeps the two icons together,
imposes proper behaviour for resizing, etc.  See later section for
details of these mechanisms.  In this document the word "item" is used
to denote a new-style item, and the word "composite" to indicate one
constructed from more than one icon.  The word "icon" is used to
denote an actual WIMP icon.

See later section for a list of the items supported.


3. User interface
=================

WinEdit is started by double-clicking on its icon.  It installs itself
on the icon bar, on the right.

If a Template file is double-clicked, it is loaded into !WinEdit, and a
document window appears.  WinEdit looks for a sibling Sprite file called
Sprites, and if it exists uses it to provide any local sprites for
this Template file.

The following descriptions include ASCII pictures of dialogue box
layouts.  These are diagrammatic and are not intended to accurately
reflect the actual appearance of the finished dialogues - for example,
the position of increment/decrement buttons is likely to be different,
according to the Style Guide.  In these diagrams, the following
conventions are used:-

* Name          Radio button.  (Infer radio groups from positioning)
# Name          Option button.
(Name)          Action button
((Name))        Default action button
Text:           Label
_____           Editable field
[value]         Display (non-editable) field
(<)             Decrement button
(>)             Increment button
(<>)            Decrement/increment button pair
(M)             Pop-up menu button


3.1. The Iconbar Icon
---------------------

The iconbar icon acts as a drag-and-drop target of files and RAM
transfers.  Dragging a Template file onto it loads that file as if it
had been double-clicked.  Dragging a Sprite file onto the icon causes
the file to be *Iconsprited.  Other file types are faulted.

The iconbar icon responds to mouse clicks as follows:-

Click SELECT: a new blank document window appears (see later)
Click ADJUST: the Palette window appears. (see later)
Click MENU: the following menu appears:-

  Info       an info box for the program
  Palette... open the tool window, same as ADJUST above
  Quit       quit the program, warning about unsaved documents

In addition WinEdit responds to Quit and Shutdown messages in the proper
way.


3.2. The Document Window
------------------------

The document window contains a filer-like listing of all the resources
in the file being edited (currently these will all be windows).  The
window title bar shows the filename, and a trailing " *" if the file
is modified.  It has a vertical scrollbar as well as close, back,
resize and toggle icons.

There is one document window per file loaded into WinEdit.  Attempts to
edit a file that is already loaded will be trapped, and instead the
existing document window for that file will be raised.  Closing a
document window removes the associated file from memory, with an
approprate warning about any unsaved data.

The resources are ordered in the order in which they appear in the
file, and the display format is fixed as large icons - sort and
display options may be added in a future version.  There will be a
number of distinct icons for different types of window:-

    Ordinary window, no scrollbars
    Ordinary window, with scrollbars
    Pane window, no scrollbars
    Pane window, with scrollbars

The intention is to give the user some useful visual cues about which
window is which - not to fully depict every possible window flag in
the icon!

Full selection and drag-n-drop behaviour is provided on the items in
this window.  Selected items are highlighted by inverting as in the
Filer.  The selection is a "single systemwide" one as required by the
new Clipboard system.

The Document Window responds to mouse clicks as follows:-

DOUBLE-CLICK SELECT on an icon:
        Open the Template Window for the resource represented by the
        icon.  If this is already open, raise it to the top of the
        window stack.

CLICK SELECT on an icon:
        Claim selection.  Select that icon, deselecting all others.

CLICK SELECT on an icon name:
        Highlights icon name and inserts caret to enable immediate editing;
        RETURN consolidates any changes, ESCAPE cancels them.

CLICK ADJUST on an icon:
        Claim selection.  Toggle selection of that icon, leaving any
        previously selected icons in this window selected.

CLICK SELECT on background: clear selection.

DRAG SELECT on background:
        Deselect any selected icons.  Display a variable-size
        shimmering box anchored at the initial click position.
        Autoscroll the window if user moves outside it.  When SELECT
        is released, claim selection and select all icons which
        intersect the final rubber box.

DRAG ADJUST on background:
        as above, but toggle the chosen icons leaving any previously
        selected icons in this window selected.

DRAG SELECT in an icon:
        If icon is not selected, then select it as in "CLICK SELECT on
        an icon" above.  Display a fixed-size shimmering box around
        all the selected icons.  Track this as user drags the mouse.
        When SELECT is released, export a Templates file composed of
        the selected resources.  The target for this may be another
        WinEdit window, another application (such as !FormEd) or a Filer
        window (in which case a generic filename like "Selection" will
        be used).  Note: if the target for the drag-and-drop is the
        source window, this is a no-op.

SHIFT-DRAG SELECT in an icon:
        Identical to DRAG SELECT, except that the operation is treated
        as a "move" rather than a "copy" - if the export operation
        succeeds, the selected resources are deleted from the source
        window.

MENU:
        If there is no selection, and we are over an icon, then make
        it a "temporary selection" as in the Filer.  Grab the caret.

        [ QUESTION: this seems to sit uneasily with the new
        one-selection-per-system model.  Do we do this even if there
        IS a selection elsewhere in the system? ]

        The following menu is opened:-

        File => Save => SaveAs dbox             Saves the whole file
                Create Header => SaveAs dbox    Creates #defines file
        Selection =>    Delete ^X               Delete selected templates
                        Save => SaveAs dbox     Save selected templates
        -------------
        Select all ^A
        Clear selection ^Z
        -------------
        New window => Name: _______     Create a new window resource.

All clicks of SELECT, ADJUST or MENU in the window cause it to gain the
caret.

Drag operations may be aborted by pressing ESCAPE.


The document window acts as a target for drag-and-drops as follows:-

If a Template file is dragged into this window, or drag-and-drop
happens from elsewhere in WinEdit, or when the Paste operation is
invoked, templates in the imported file or clipboard are added to this
one.  Any resource name clashes when importing templates will be
resolved by appending a disambiguating number to the name, as, eg,
"SaveAs.1".

If a Sprite file is dragged into this window it is used to provide
local sprites, before looking in the Wimp sprite pool.  This Sprite
file will not be stored when the Templates file is saved; it is
intended for quickly checking the appearance of a window with
different sets of button sprites, etc.  [ Yes? ]


3.3. The Template Window
------------------------

The Template Window displays and edits a Window resource in a WYSIWYG
fashion.  Its colours, titlebar, scrollbars, close icon and other WIMP
border icons thus reflect the state of the window's flags and will
differ from window to window.  Because this could make manipulating
the window difficult, there are menu options for some of the common
window management operations (see later).

The user may have many Template windows open at once, but only one for
each resource in the file - attempts to edit a resource that is
already open will cause the appropriate Template window to be raised
instead.

The work area of the window shows all the icons defined in the
template in their proper positions.  In a departure from FormEd, the
icons will be displayed by WinEdit rather than by the Wimp, and WinEdit
will not try to emulate their runtime behaviour.  Instead all icons
will be directly draggable and resizeable, as detailed below.

[ Aside: could still implement the window with actual Wimp icons.
This would simplify the code for detecting mouse clicks, and make most
of the redrawing automatic. It might make drawing the selection
borders harder, though, as they need to surround whole composite
items.  In any case, the icons will not emulate their runtime
behaviour. ]

Full selection and drag-n-drop behaviour is provided on the items in
this window.  Selected items are highlighted by surrounding them with
a border and "ears" for resizing.  The border drawn for a composite
item shall be around the bounding box of the whole item, not the
individual icons that form it.  The selection is a "single systemwide"
one as required by the new Clipboard system.

The Template Window responds to mouse clicks as follows:-

DOUBLE-CLICK SELECT on an icon:  [*** not implemented ***]
        If the icon contains editable text, place the caret in the
        icon and allow the user to edit it in-place.  When the user
        presses RETURN resize the icon (or the whole item if
        appropriate) to fit the text.  ESCAPE (or losing the caret)
        aborts the editing operation and resets the text to its
        original value.  This operation is available on all icons
        containing user-specifiable text.

SHIFT-DOUBLE_CLICK SELECT on an item:
        Open the Item Properties window for the item.  See below for
        details.

CLICK SELECT on an item:
        Claim selection.  Select that item, deselecting all others.

CLICK ADJUST on an item:
        Claim selection.  Toggle selection of that item, leaving any
        previously selected items in this window selected.

CLICK SELECT on background:
        clear selection.

DRAG SELECT on background:
        Deselect any selected items.  Display a variable-size
        shimmering box anchored at the initial click position.
        Autoscroll the window if user moves outside it.  When SELECT
        is released, claim selection and select all items which
        intersect the final rubber box.

DRAG ADJUST on background:
        as above, but toggle the chosen items leaving any previously
        selected items in this window selected.

DRAG SELECT in an item:
        If item is not selected, then select it as in "CLICK SELECT on an
        item" above. Display a fixed-size shimmering box around all the
        selected items.  Track this as user drags the mouse.  When SELECT
        is released, the exact behaviour depends on the target window:

        Same WinEdit window: *move* the selected items to the new position

        Different RedEd window: *copy* the selected items to the new
        window, putting them in the indicated position.  Adjust icon
        numbers as required.

        Other: export a Templates file containing one window resource.
        The window shall contain a *copy* of the selected items.  The
        window shall be sized to fit the final size of the shimmering
        box, and have a pre-defined set of window flags/colours.

SHIFT-DRAG SELECT in an item:
        Identical to DRAG SELECT, but with "move" and "copy" reversed,
        so that drags within the same window do a copy, and drags
        outside do a move.

DRAG SELECT in a resize handle:
        Resize the selected item(s).  The visual feedback for a resize
        operation will be a variable-sized shimmering box, bounded at
        the side or corner opposite the resize handle.  When the user
        releases SELECT, the item will be resized to fit the final
        box.  Composite items will be resized according to their
        particular layout strategy - see later.

CTRL-SHIFT-DRAG SELECT:  [*** not implemented ***]
        Move window.  This is provided so that the user can easily
        move windows which have no title bar.  Raises the window to
        the top of the stack first.

CTRL-SHIFT-DRAG ADJUST:  [*** not implemented ***]
        Move the window without altering its stacking order.


MENU
        If there is no selection, and we are over an icon, then make
        it a "temporary selection" as in the Filer.  Grab the caret.

        [ QUESTION: this seems to sit uneasily with the new
        one-selection-per-system model.  Do we do this even if there
        IS a selection elsewhere in the system? ]

        The following menu is opened (see later for descriptions of the
        various dialogues mentioned) :-

        Window    =>  Properties...  ^W    open window properties
                      Colours...     ^C    open window colours dialogue
                      Extent...      ^E    open extent dialogue
                      Grid...        ^G    open grid dialogue
                      Renumber icons       renumber icons
                      Close         ^F2    close template window

        Selection =>  Delete         ^X    delete selected items
                      Align          =>    align items
                      Sort           ^S    sort selected items
                      -----------------
                      Properties...  ^P    open item properties dialogue

        ------------------
        Select all      ^A
        Clear selection ^Z
        ------------------
        Test            ^T     makes items "live"


All clicks of SELECT, ADJUST or MENU in the window cause it to gain the
caret.

Drag operations may be aborted by pressing ESCAPE.

If Grid Lock is active, then the Move and Resize operations will snap
to the grid as appropriate.  Note that the shimmering box itself does not
snap as you move it around - it is felt that this provides a rather lumpy
feel.  The items snap to the grid at the end of the drag only.

The Template Window acts as a target for drag-and-drops as follows:-

If one or more items are dragged in from another WinEdit template
window, or from the Palette window, they are added to this window; see
description of DRAG SELECT above.

If a Template file is dragged into this window then a copy of its
items are added to this window.  (If it contains more than one Window
resource, only the first is used).  The new items are placed in the
relative positions indicated in the imported file, with the top-left
corner of the imported window's bounding box at the top left corner
of the window.

The WIMP border icons may be used to manipulate the window's size,
position and scroll offsets.  THIS INFORMATION IS SAVED WITH THE
TEMPLATE.  The stacking position is not saved; all templates are saved
with a stacking position of -1 (top of stack) unless the window's
Backdrop flag is set, in which case the position is -2 (bottom of the
stack).


3.4. The Sort option
--------------------

Sort re-numbers the selected writable icons so that the icon numbering
is "correct" for the Wimp's KAT validation command (which automatically
moves the caret on up/down arrows and tab/shift-tab; you have to add
KAT to the validation string yourself).  Unfortunately the Wimp does
not let you specify the icons you want to traverse to; it just goes
to the next available writable icon in icon number order.  Hence the
provision of this option.

The ordering imposed is Top->Bottom, Left->Right so tabbing takes you
across the screen and then down to the next line when the rightmost
icon is reached.  The ordering is determined by comparing the bounding
boxes using a qsort callback function the exact details of which I
forget.  It probably works best when the icons are placed in a more or
less regular grid.

Any non-writable icons that are selected are not renumbered, so it is
OK to go Select All, Sort.  Also because it works by swapping icon numbers
between the selected writables it will not alter the icon numbers of
any other object.


3.5. The Align sub-menu
-----------------------

This provides the ability to align a number of selected items in a
template window.

To align a selection, menu on any item and choose an alignment option
from the submenu; the stated alignment is then performed relative to
the menu'd item (which may or may not be in the selection).

The alignment options are:

  Left edges
  Right edges
  Horiz. centres
  --------------
  Top edges
  Bottom edges
  Vert. centres
  Baselines


3.6. The Grid Dialogue
----------------------

The Grid dialogue lets the user control the characteristics of the
alignment grid.  It is opened when the user types ^G, or selects
"Grid..." from the Template Window's menu.  You can only open one copy
of the the Grid dialogue; it always refers to the "current" Template
window - the one that most recently received any mouse click.  If you
leave it open and click in a different Template window, the Grid
dialogue will be updated reflect the new window's grid.

The dialogue contains the following:-

                Grid for "mywin"
        -----------------------------------
        Spacing ______ (<>) OS units
        Crosses ______ (<>) grid points apart
        Colour [    ] (M)
        # Show grid  # Lock to grid
                           (Cancel)  ((OK))


3.7. Distribute Dialogue      [*** not implemented ***]
------------------------

This provides the ability to evenly space a number of selected items
in a Template Window.  It is a singly-instatiated dialogue, and always
affects the window containing the selection.

The dialogue contains the followimg:-

                        Distribute Selection
        -----------------------------------------------------
        Horizontal:
        * As Is
        * Evenly spaced centres
        * Gap of: _____ between: * edges * centres

        Vertical:
        * As Is
        * Evenly spaced centres
        * Evenly spaced baselines
        * Gap of: _____ between: * edges * centres * baselines
        
        ((OK))  (Cancel)

Pressing OK causes all the selected items to be repositioned as
specified by the settings of the dialogue:-

        If an "Evenly" option was chosen, they are moved so that the
        space between the topmost and bottomost items (or
        left/rightmost) is evenly shared between the items.

        If a "Gap of" option was chosen, the items are moved such that
        there is the specified gap between neighbouring items.

In both cases the items are kept in the same order, as judged by
comparing the positions of their centres.  The objects are left
selected so that the user can then fine-tune their position as a
group.

Grid Lock is ignored for the purposes of Align and Distribute
operations.


3.8. Extent Dialogue
--------------------

This allows the user to view and alter the "extent" of a Template -
that is, the size of its virtual work area as opposed to its physical
size.  It is opened when the user types ^E, or selects "Extent..."
from the Template Window's menu.  It always refers to the "current"
Template window - the one that most recently received any mouse click.
If you leave it open and click on a different Template window, the
Extent dialogue will be updated to reflect the new window's extent.

The dialogue contains an "adjustable square" with numeric readouts
which are also editable, as well as the following buttons:-

        (Clip)          make extent = window size
        (Cancel)        abandon dialogue
        ((OK))          apply current settings

There are also two writable fields to set a minimum window size:

    Minimum width  ________
    Minimum height ________

  [what do these do?]


3.9. Window Properties Dialogue
-------------------------------

This is a singly instantiated dialogue for displaying and editing the
properties of windows.  While it is open it always displays the
properties of the most recently clicked Templates window.

The Window Properties dialogue would be badly cluttered by the
need to support editing of both old-style and new-style window flags.
Therefore only new-style flags are supported.  If old-style flags are
encountered when loading a template they are converted to equivalent
new-style ones.
Would it be acceptable to only provide for the editing of new-style
ones, and forcibly convert old-style flags to new ones on input?

Even so, there are still a lot of things to edit!
        Moveable
        Auto-redraw
        Pane
        No bounds
        User scroll: Off, Autorepeat, Debounced
        Real colours
        Backdrop
        Hot keys
        Button type of work area
        Back icon
        Quit icon
        Title icon -> huge number of icon flags, yuck!
        Toggle icon
        V Scroll
        H Scroll
        Size icon
        Colours: title fg/bg, work fg/bg, scroll fg/bg, input focus

This is a lot to put in one dialogue box!  It is also out of keeping with
the philosophy of the icon properties windows; it exposes ALL of the WIMP
flags.

Proposed simplifications:-

* Get rid of most title options.  Allow user to specify text
    and indir length only.
* Title text shall be centered.
* Enforce title & focus colours as per style guide
* Enforce standard scrollbar colours
* Put button type of work area on a pop-up choice
    (shame to expose it really)


Here is the proposed layout.

                   Window Properties
        ---------------------------------------------------------------
        Gadgets:
           # Title: _____________ Max length: ___
           # Back   # Close   # Toggle # H scroll   # V scroll   # Size
        Flags:
           # Pane   # Moveable   # Allow offscreen   # Real colours
           # Backdrop   # Hot keys   # Auto-redraw
        User Scroll:
           * Off  * Autorepeat  * Debounced
        Button type: [ Click ] (M)
                                                      (CANCEL)   ((OK))

Note that the title defaults to the standard colours, justification
etc, and must be textual only.  The standard colours might be
ascertained by looking in a ROM template file known to be trustworthy.

However, window colours can be changed by using the Colours dialogue.


3.10. The Colours dialogue
--------------------------

This is used to change a window's colours.

  Titlebar:-
    Foreground  [    ] (M)
    Background  [    ] (M)
    Focus       [    ] (M)
  Work area:-
    Foreground  [    ] (M)
    Background  [    ] (M)
  Scroll bars:-
    Foreground  [    ] (M)
    Background  [    ] (M)
           (Cancel)  ((OK))


3.11. Item Properties
--------------------

Properties of individual items are displayed and altered with these
windows.  There is am Item Properties window specific to each sort of
item, called Label Properties, Slider Properties, etc.  There is only
ever one Item Properties window on display; as you select different
items it is updated to show the properties of the new item.

[ You can't edit the props of a number of similar items all at once; I
think with the restricted number of settable properties we are
allowing, that would not gain you very much. ]

Each Item Properties dialogue is discussed in the section about the
corresponding item.


3.12.  The palette window
-------------------------

This is used for creating new icons. It is a window like a template
window, with an example of each type of item (except an unrecognised
icon). To create new items, simply drag them from this window into
position.

[ Aside: In effect this is just like a read-only template window from
some unseen template file. Indeed, it is implemented as such ]



4. Items
========

Many items seem to have a standard height - perhaps the user should not
be able to change it?

The property windows shown below include an additional window controlled
by the action button "Details...". This is to reduce complexity of the
dialogues; these options are seldom used.  If the user switches on
"Details...", the additional window remains open until explicitly closed,
even if the user selects a different item.

All the property windows below have OK and Cancel buttons with the usual
functions, and all additional windows have a Close action button.  They
are not shown in the diagrams to save space.


4.1. Default action button
--------------------------

This is a rectangular button with the standard colours as specified by
the Style Guide.  It has a visually distinguishing border to show that
it is the default button (ie, activated by Return).

It is implemented as a single WIMP icon.

Its label may be text, sprite or both.  The label will be centered
horizontally and vertically.

For alignment purposes, the item's baseline shall be the bottom of the
text (or where the bottom of the text would be for a sprite-only
icon).

[ Do we want to offer a choice of alignment options for the text and/or
  sprite? I think we always want action button labels to be centered.
  Style Guide? ]

Its Item Properties dialogue contains the following:-

                Default Action Button Properties
        ----------------------------------------------
        Name: ______________
        Text:   ___________  
        Sprite: ___________

        (Details...)

        Width:  [www] (<>)   Height: [hhh] (<>)
        Font: [fontname   ] (M) at [nn] (<>) pts
        Icon number:  ____


4.2. Action Button
------------------

As for the Default Action Button, but without a highlighted border.  The
properties dialogue is identical.

[ Do we want to offer a choice of alignment options for the text and/or
  sprite? I think we always want action button labels to be centered.
  Style Guide? ]


4.3. Label
----------

For labelling other fields in the window.  Background colour of the
label is always the same as the window background - editor maintains
this automatically (or else uses Transparent).  We allow the user a
limited choice of alignment options: need style guide advice on which
are recommended; depends on whether text and/or sprite used, eg:-

Name    Text            Sprite          Text + Sprite
---------------------------------------------------------------
Left    Left just       Left just       Text left, Sprite right
Right   Right just      Right just      Text right, Sprite left
Centre  Centred         Centred         Both centred

It is implemented as a single WIMP icon.

Its Item Properties dialogue contains the following:-

                        Label Properties
        ----------------------------------------------
        Name: ______________
        Text:   ___________  
        Sprite: ___________
        Justify: * left  * right  * centre

        (Details...)

        Width:  [www] (<>)   Height: [hhh] (<>)
        Font: [fontname   ] (M) at [nn] (<>) pts
        Icon number:  ____


4.4. Display Field
------------------

For the application to display a value.  Visually highlighted e.g.
by troughing; see Style Guide.  A Display Field may contain text or
a sprite, formatted according to the Justify property.

Standard colours as per Style Guide - user should not be able to alter
them.  The Display Field item is implemented as one WIMP icon.

Alignment: baseline is at the bottom of the text.

Its Item Properties dialogue contains the following:-

                    Display Field Properties
        ----------------------------------------------
        Name: ______________
        Text:   ___________  
        Sprite: ___________
        Justify: * left  * right  * centre

        (Details...)

        Width:  [www] (<>)   Height: [hhh] (<>)
        Font: [fontname   ] (M) at [nn] (<>) pts
        Length: ____ (<>)
        Icon number:  ____

Alternative versions with a pop-up menu button or adjuster buttons
will probably be provided as well.


4.5. Writeable field
--------------------

For the application to display values that are editable by the user.
Visually highlighted e.g. by plinthing.  May only contain text.
Background filled, colours dictated by Style Guide and not changeable.
The Writeable Field item is implemented as one WIMP icon.

Alignment: baseline is at the bottom of the text.

Its Item Properties dialogue contains the following:-

                   Writeable Field Properties
        ----------------------------------------------
        Name: ______________
        Text:   ___________  
        Valid: ________________
        Justify: * left  * right  * centre

        (Details...)

        Width:  [www] (<>)   Height: [hhh] (<>)
        Font: [fontname   ] (M) at [nn] (<>) pts
        Length: ______ (<>)
        Icon number:  ____


There may also be a case for providing a version with up/down arrows
or a popup menu button attached - however this seems like a fairly
rare thing for a writeable item to need, and the buttons can always
be added separately.  In the first instance such an item will not be
provided.


4.6. Slider
-----------

Composed of up three - the well, track and knob Need style guide input
on nature of well and knob - we believe that red=input/output,
green=output only.  Might want control of the colour of the well/knob
for specialised applications (eg, a colour selector).

Alignment: baseline at such a position that it aligns nicely with a
label to the left.

Sizing: the object may be resized horizontally, in which case the well
is the part that grows/shrinks.

Stacking: the knob must stack above the well.  What do we do when user
deliberately renumbers them otherwise?

Its Item Properties dialogue contains the following:-

                        Slider Properties
        ----------------------------------------------
        Name: ______________

        (Details...)

        Width:  [www] (<>)   Height: [hhh] (<>)
        Icon numbers:
                Well: ____  Track:____  Knob: ____

NOTE: There will also be a Vertical Slider with an identical
properties window.


4.7. Option button
------------------

Composed of one icon.  The label must be text, since the sprite is
taken up by the on/off indicator.

Alignment: baseline is at the text's baseline.  The label is to the
right of the sprite.

Its Item Properties dialogue contains the following:-

                   Option Button Properties
        ----------------------------------------------
        Name: ______________
        Text: ______________
        # Selected

        (Details...)

        Width:  [www] (<>)   Height: [hhh] (<>)
        Font: [fontname   ] (M) at [nn] (<>) pts
        Icon number:  ____

The Selected option lets you choose whether the button is on or off to
start with.


4.8. Radio button
------------------

Composed of one icon.  The label must be text, since the sprite is
taken up by the on/off indicator.

Alignment: baseline is at the text's baseline.  The label is to the
right of the sprite.

Its Item Properties dialogue contains the following:-

                   Radio Button Properties
        ----------------------------------------------
        Name: ______________
        Text: ______________
        # Selected

        (Details...)

        Width:  [www] (<>)   Height: [hhh] (<>)
        Font: [fontname   ] (M) at [nn] (<>) pts
        ESG: [nn] (<>)
        Icon number:  ____

The Selected option lets you choose whether the button is on or off to
start with.  The Radio Group entry corresponds exactly to the icon's
ESG.


4.9. Group box
--------------

Two icons with special properties that make them into a visual
grouping box.  Does not act as a group in the Draw sense.

The lower icon is as large as the box, and is merely a border (or a
predefined graphic, probably a channel).  It has predefined colours
(its background always matches the window's).  The upper icon carries
the label, and is automatically positioned towards the top left of the
border.  The two icons move as a pair.

Stacking: the label must stack above the border.  What do we do when
user deliberately renumbers them otherwise?

On creation and renumbering, group boxes are kept right down at the
bottom of the stack.  This is much easier than trying to spot which
icons really need to be above them!

Its Item Properties dialogue contains the following:-

                     Group Box Properties
        ----------------------------------------------
        Name: ______________
        Text: ______________

        (Details...)

        Width:  [www] (<>)   Height: [hhh] (<>)
        Font: [fontname   ] (M) at [nn] (<>) pts
        Icon numbers:
                Frame: ____  Label:   ____



4.10. Pop-up menu button
------------------------

A single icon containing a rightwards-pointing arrow.  Juxtaposed
with other items, usually a display field, to anchor a pop-up choice
menu.

The icon is a standard size and cannot be resized by dragging.

Its Item Properties dialogue contains the following:-

                     Menu Button Properties
        ----------------------------------------------
        Name:  ______________

        (Details...)

        Icon number: ____



4.11. Value adjuster buttons
----------------------------

A pair of icons containing small arrow icons.  These may be
juxtaposed with some other item(s) with the intention that the
arrows increment and decrement a value.  The arrow icons used are as
specified by the Style Guide and cannot be changed by the user.

The item is a standard size and cannot be resized by dragging.

Its Item Properties dialogue contains the following:-

                   Adjuster Button Properties
        ----------------------------------------------
        Name:  ______________

        (Details...)

        Icon numbers:-
                Down:  ____  Up:  ____



[ TO DO:
        Display field with adjuster buttons
        Display field with pop-up menu
        Writeable field with above?
]


4.12. Wimp icon
---------------

This is the "escape mechanism"!


        Name ___________________
        Type  # Text  # Sprite  # Indir
        Contents ________________
        Valid ___________________
        Length ____ (<>)

        (Details...)

        Width:  [www] (<>)   Height: [hhh] (<>)
        Font: [fontname   ] (M) at [nn] (<>) pts
        Icon number:  ____
        Flags:-
          # Border  # Filled  # Help  # Half size
          # H-centred  # V-centred  # R-justified
          # Allow ADJUST  # Shaded  # Selected
        Colours:-
          Foreground [    ] (M)
          Background [    ] (M)


        
Technical details
=================

[ Exact details of the info stored in validation strings not yet decided ]

Information about items is stored in the validation strings
of the icons concerned.   The following information is stored for
each item

 * name (user-assigned; one per item, not one per icon)
 * type (system-assigned; one per object type)
 * if it's composite, a list of the icons which make it up.

In a composite item , the name and type information is stored only
once, in the first or "master" icon of the item.  The subsequent or
"slave" icons have their numbers recorded in the master's validation
string; application programs or libraries can use this information
to determine all the icons in the item.

SIMPLE ITEM
-----------

Name (string)
Type (string)

COMPOSITE ITEM
--------------

Master icon:
        Name (string)
        Type (string)
        Icons (comma-separated list of icon numbers)

Slave icon:
        No data stored

The comma-separated list of icon numbers is in a pre-determined
order which implicitly specifies which icon is which sub-part of the
composite.  This ordering is part of the definition of each
composite item type.  Any optional icons which the WinEdit user has
configured "off" are are given the value -1 as a placeholder - the
application should be aware of this possibility and avoid supplying
this value in WIMP calls.

The user supplies only the Name field; the other fields are filled
in automatically by WinEdit.


NAMESPACE
---------

Names and Types occupy separate string namespaces.  They may contain
any characters subject to the constraints implied by being stored in
validation strings.

Types are system-assigned identifiers for item types; for example,
"slider".  Names are user-assigned identifiers for item instances; for
example, "blue".

We will requisition one character in the WIMP's validation string namespace.
Let's suppose this is N, which does not seem to be taken.  We then define
sub-codes:-

Single icon:-
   N1name/type
Master icon:-
   NMname/type/iconlist

The parameters must appear in the order shown.  Names and types are
composed from the characters A-Za-z0-9_ and are separated from each
other by slashes.  The whole command is terminated by a semicolon or
the end of the string.

The iconlist is the comma-separated list of icon numbers mentioned
previously.


RENUMBERING
-----------

Some editing operations cause automatic renumbering of some or all
icons.  When this happens composite items will be renumbered in such
a way that their layering is maintained correctly.  The user will be
able to manually renumber icons; this will be done inside the
appropriate item's editing window.  However no special treatment
will be given to manually renumbered icons; they will be candidates
for renumbering later.  The user will just have to be careful, or
better still rework their code to look up the icon numbers at
runtime.


All icons are indirected.



*****************************************************************************

TODO
----
Check RISCOS_Lib usage of specific icon numbers!
Palette window
Standardise labels in the various item props windows (where possible).

NOTES
-----
Copy design of resize ears from Impression/Draw


QUESTIONS
---------

Exact behaviour of "implicit selections" in the new single-selection
model.

Is it really necessary to provide all the button types for the work area?


STYLE-GUIDE INPUT NEEDED
------------------------

What title bar formats do we advise?  Can we kill sprites in titles, eg?
        Centred text
What title bar, focus and scrollbar colours do we advise?
        Enforce standard ones, pick them up from a well-known system
        Templates file
What justification options do we want for action buttons?
        The ones that I put in

WEAKNESSES
----------

I don't like the menu in the Document window.  There is a mixture of old and
new that does not seem to sit comfortably ("Cut/copy/paste" vs. "Rename =>")

The Window menu has two Properties entries!  Need to fix this.

FUTURE ENHANCEMENTS
-------------------

Drag-n-drop within the Document Window: allow user to reorder
templates.  Drag-n-drop from other windows: the data is inserted in
the file at the position of the mouse pointer when the drop finishes.

[ Are these useful?  After all, resources are looked up by name;
ordering should not be particular significant.  And there's no
precedent for this in the Filer ]


Document window: support direct renaming of templates by clicking
and typing.  Pro: nice.  Con: how often do you rename templates?
If we do this, get rid of "New template => <typein>"; instead
have "New template    ^N" which creates an template with an "untitled"
name, and let user rename as above.

Better UI for setting window extent.
